--- title: SAIF.Business.View.Provider architecture summary: Architectural responsibilities, boundaries, and interaction patterns. status: draft owner: SAIF Doc Gen last_reviewed: 2026-08-21 library: SAIF.Business.View.Provider reference_type: embedded --- # SAIF.Business.View.Provider architecture `SAIF.Business.View.Provider` is a read-only business/view layer library in the SAIF BOF "View" family. It exposes the provider subject area — providers, provider locations, addresses, tax IDs, relationships, ineligibility periods, provider types, MCO enrollments, services, service contracts, and DCBS cost-charge factors — as strongly typed objects for claim/legal application consumers, without any create, update, or delete capability. ## Responsibilities - Expose the SAIF provider subject area (providers, provider locations, addresses, tax IDs, relationships, ineligibility periods, provider types, MCO enrollments, services, service contracts, DCBS cost-charge factors) as read-only, strongly typed objects for claim/legal consumers. - Enforce read-only construction: every `IBusinessCriteria` implementation throws `ApplicationException(clsConstants.Messages.InvalidSQLProperty)` from `CreateSQL`, `InsertSQL`, `UpdateSQL`, and `DeleteSQL`; `clsProvider.GetProvider` additionally sets `ReadOnly = True` on the returned instance.* - Provide multi-criteria provider-location search (`clsProviderSearch`) independent of the criteria/portal pattern used elsewhere in the library. - Attach MCO plan information to enrollments and service contracts via the cross-library call `GetMCOInfo(dpi)` (from `SAIF.Business`). ## Component boundaries - **Portal/criteria business objects** (`clsProvider`, `clsProviderCollection`, `clsProviderLocation`, `clsProviderLocationCollection`, `clsProviderAddress`, `clsProviderAddressCollection`, `clsProviderRelationship`, `clsProviderRelationshipCollection`, `clsProviderIneligibilityPeriod`, `clsProviderIneligibilityPeriodCollection`, `clsProviderTaxID`, `clsProviderTaxIDCollection`, `clsProviderType`, `clsProviderTypeCollection`): subclass `clsBusinessBase`/`clsBusinessCollection(Of T)`, each with a nested `Criteria` class, retrieved through `IDataPortalInfo.DataAccessLayer.RetrieveObject(criteria)`. - **Direct-query self-loading lists** (`clsDCBSCostChargeList`, `clsMCOProviderList`, `clsProviderServiceList`, `clsProviderServiceContractList`): plain `List(Of T)` subclasses that build SQL with `Text.StringBuilder` and execute it via `SqlHelper.ResultSetQuery` in their constructor, bypassing the criteria pattern. - **Search engine** (`clsProviderSearch`, `clsSearchCriteria`, `clsProviders`, `clsSearchResults`): a standalone multi-criteria search component that builds and executes dynamic SQL directly. - **Generated typed DataSet** (`Institutions` / `InstitutionDataTable` / `InstitutionRow`): compiled into the assembly but unreferenced by any other type in the library; residual scaffolding paired with the `SAIF.Legacy.BankValidator` package reference.* - **Aggregate roots**: `clsProvider` (keyed by `PROVIDER_SEQ_NUM`) and `clsProviderLocation` (a second root that back-navigates to its `Provider`), each exposing lazily-loaded child navigation properties. ## Interaction model - Claim/legal application managers (`SAIF.Application.Claim.Legal`, `SAIF.Business.Claim.Legal`) call the public `Get*` factory methods, supplying an `IDataPortalInfo` obtained from the caller's data-portal context. - Portal/criteria objects delegate retrieval to `IDataPortalInfo.DataAccessLayer.RetrieveObject(criteria)`, which executes the criteria's `RetrieveSQL` and populates the object through `BeforeRetrieve`/`AfterRetrieve` lifecycle methods. - Direct-query lists and the search engine execute SQL themselves via `SqlHelper.ResultSetQuery`, independent of the data-portal criteria pipeline. - Navigation properties (e.g. `clsProvider.ProviderLocations`, `clsProviderLocation.Addresses`, `ChildRelationships`, `IneligibilityPeriods`, `DCBSCostCharges`, `MCOList`, `Services`, `ServiceContracts`) are lazily loaded — each access triggers its own database round trip (a per-property N+1 pattern).* - Reciprocal navigation (`clsProvider.ProviderLocations` → `clsProviderLocation.Provider` → `clsProvider`) forms a cycle broken only by lazy-load null checks; nothing is cached across instances.* - The only outward cross-library call is `GetMCOInfo(dpi)` (from `SAIF.Business`), used to attach `MCOPlanInfo` to MCO enrollments and service contracts. - Consumers reference this library through the packaged assembly `SAIF.BOF.Business.View.Provider` 2.0.23139.2 (binary ``), not through a project reference; documented consumers include `SAIF.Application.Claim.Legal` (`LegalManagerBase`, `clsCaseCostManager`, `clsRequestManager`) and `SAIF.Business.Claim.Legal` (`clsCaseCost`). ## Architecture diagram The following diagram shows the high-level component interactions between claim/legal consumers, this library's two data-access styles, and the underlying SAIF BOF framework/data layer. ```mermaid flowchart TD A[Claim/legal application managers
SAIF.Application.Claim.Legal / SAIF.Business.Claim.Legal] --> B[Portal/criteria business objects
clsProvider, clsProviderLocation, etc.] A --> C[Direct-query self-loading lists
clsDCBSCostChargeList, clsMCOProviderList,
clsProviderServiceList, clsProviderServiceContractList] A --> D[clsProviderSearch] B --> E[IDataPortalInfo.DataAccessLayer.RetrieveObject] C --> F[SqlHelper.ResultSetQuery] D --> F E --> G["SAIF BOF Framework / Oracle
data access"] F --> G B --> H[SAIF.Business.GetMCOInfo] ``` ## Sequence diagram The following diagram shows the primary retrieval sequence for a portal/criteria business object (e.g. retrieving a provider location and its navigation properties). ```mermaid sequenceDiagram participant Client participant clsProviderLocation participant Criteria participant IDataPortalInfo Client->>clsProviderLocation: GetProviderLocation(dpi, providerLocationID) clsProviderLocation->>Criteria: new Criteria(providerLocationID) clsProviderLocation->>IDataPortalInfo: DataAccessLayer.RetrieveObject(criteria) IDataPortalInfo-->>clsProviderLocation: populated object (AfterRetrieve) clsProviderLocation-->>Client: clsProviderLocation instance Client->>clsProviderLocation: Addresses (lazy navigation) clsProviderLocation->>IDataPortalInfo: RetrieveObject(AddressCollection criteria) IDataPortalInfo-->>clsProviderLocation: clsProviderAddressCollection clsProviderLocation-->>Client: Addresses ``` ## Design constraints - Read-only by construction: no `CreateSQL`, `InsertSQL`, `UpdateSQL`, or `DeleteSQL` is implemented; all such properties throw. - Two coexisting data-access styles (portal/criteria vs. direct-query) mean consumers must understand which retrieval path a given type uses. - Lazy-loaded navigation properties create a per-property N+1 database round-trip pattern.* - `clsProviderCollection.Criteria.BuildSQLWhere` builds SQL by string concatenation for tax-ID lists and caller-supplied WHERE clauses, which is unparameterized and a potential SQL-injection path if callers pass untrusted input (see [BR-PRV-003](business-rules.md#br-prv-003-provider-set-retrieval-uses-unparameterized-sql)). - No configuration, logging, caching, or security/authorization logic is implemented in this library; all environmental context arrives via the injected `IDataPortalInfo`. ## Related documentation - [Index](index.md) - [Overview](overview.md) - [Dependencies](dependencies.md) - [Operations and processes](operations-processes.md) - [Business rules](business-rules.md) - [Database tables](database-tables.md) - [SQL catalog](sql/index.md) - [API reference](api/index.md) > **Note:** Statements marked with * were inferred from code structure, naming conventions, or > contextual evidence where direct confirmation was not available in source artifacts. Statements > marked with ** could not be confirmed; treat as unknown until verified. ## Sources - `SAIF.Business.View.Provider/SAIF.Business.View.Provider.vbproj` - `SAIF.Business.View.Provider/clsProvider.vb` - `SAIF.Business.View.Provider/clsProviderCollection.vb` - `SAIF.Business.View.Provider/clsProviderAddress.vb` - `SAIF.Business.View.Provider/clsProviderAddressCollection.vb` - `SAIF.Business.View.Provider/clsProviderLocation.vb` - `SAIF.Business.View.Provider/clsProviderLocationCollection.vb` - `SAIF.Business.View.Provider/clsProviderRelationship.vb` - `SAIF.Business.View.Provider/clsProviderRelationshipCollection.vb` - `SAIF.Business.View.Provider/clsProviderSearch.vb` - `SAIF.Business.View.Provider/clsProviderServiceContract.vb` - `SAIF.Business.View.Provider/clsProviderServices.vb` - `SAIF.Business.View.Provider/clsProviderTaxID.vb` - `SAIF.Business.View.Provider/clsProviderTaxIDCollection.vb` - `SAIF.Business.View.Provider/clsProviderType.vb` - `SAIF.Business.View.Provider/clsProviderTypeCollection.vb` - `SAIF.Business.View.Provider/clsProviderIneligibilityPeriod.vb` - `SAIF.Business.View.Provider/clsProviderIneligibilityPeriodCollection.vb` - `SAIF.Business.View.Provider/clsDCBSCostCharge.vb` - `SAIF.Business.View.Provider/clsMCOProvider.vb` - `SAIF.Business.View.Provider/app.config` - `SAIF.Business.View.Provider/Web.config` - `SAIF.Business.View.Provider/packages.config`